A-API调用概述

一、API调用概述

此章节主要从 XAPP SDK 的最简单的使用流程上介绍如何快速使用 XAPP SDK，包括了 XAPP SDK 最简单的初始化以及基本流程中常用的任务简单介绍与使用。

二、XAPP SDK简单初始化

XAPP SDK 初始化的参数有相对较多的可选参数，可以根据需要设置使用。这里介绍最简单的初始化过程（使用默认参数初始化使用）。

//使用默认参数初始化
XLinkConfig config = new XLinkConfig.Builder().build();
XLinkAndroidSDK.init(config);
 
//启动并运行SDK
XLinkSDK.start();
 
//停止当前SDK
XLinkSDK.stop();
//退出用户登录状态，清除用户信息，并停止当前SDK
XLinkSDK.logoutAndStop();

XAPP SDK 启动后即可进行相关功能使用。

三、基本流程任务使用

XAPP SDK 中提供了多个模块与功能，以下仅从最常见的使用流程进行基本介绍。最常见的使用流程为：

登录账号->扫描设备->添加订阅设备->设备控制->移除设备（->同步设备列表）

1、登录账号

登录账号使用XLinkUserAuthorizeTask，使用注册到的 APP 账号进行登录，该账号可通过 demo 注册进行获取；登录时需要 CropId，即企业ID，获取方式请参考资源准备

XLinkUserAuthorizeTask authTask = XLinkUserAuthorizeTask.newBuilder()
    //设置登录账号所属的企业ID
    .setCorpId("xxxx")
    //不管是手机还是邮箱登录，都可以设置上去，登录时并不区分是手机还是用邮箱
    .setPhone("13813813800", "123456")
    //如果需要设置手机区号则设置，默认为中国大陆手机区号+86，非中国手机号则需要设置
    .setPhoneZone("+86")
    .setEmail("test@xlink.cn","123456")
    .setListener(new TaskListXLinkTaskListnerener<UserAuthApi.UserAuthResponse>() {
            @Override
            public void onError(XLinkCoreException xLinkErrorCode) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(UserAuthApi.UserAuthResponse result) {
                //登录成功返回用户信息结果
            }
    })
    .build();
XLinkSDK.startTask(authTask);

2、扫描设备

扫描设备使用XLinkScanDeviceTask，扫描设备需要使用到设备的 ProductId，即产品ID，获取方式请参考资源准备

XLinkScanDeviceTask scanTask = XLinkScanDeviceTask.newBuilder()
        // 设置超时，单位毫秒，默认90秒, 建议使用60-90秒,根据需要可适当调整
        .setTotalTimeout(60000)
        //设置扫描的目标PID,可同时设置多个,不支持null与空字符串
        .setProductIds("xxx","xxx")
        //设备搜索回调
        .setScanDeviceListener(new XLinkScanDeviceListener() {
            @Override
            public void onScanResult(XDevice xDevice) {
                // 同一设备默认仅会回调一次
            }
 
            @Override
            public void onError(XLinkCoreException xLinkErrorCode) {
            }
 
            @Override
            public void onStart() {
            }
 
            @Override
            public void onComplete(Void aVoid) {
            }
        }).build();
XLinkSDK.startTask(scanTask);

3、添加订阅设备

添加订阅设备时会绑定当前用户与设备的关系，使用XLinkAddDeviceTask

XLinkAddDeviceTask addTask = XLinkAddDeviceTask.newBuilder()
        //设置需要添加的设置,一般来自扫描得到的设备对象
        .setXDevice(device)
        // 设置本次订阅任务的回调
        .setListener(new XLinkTaskListner<XDevice>() {
            @Override
            public void onError(XLinkCoreException xLinkErrorCode) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(XDevice xDevice) {
                //订阅成功返回设备对象
            }
        })
        .build();
XLinkSDK.startTask(addTask);

4、设备控制

设备控制分为两个操作，分别是获取数据端点和设置数据端点操作，两个操作分别对应了两个任务。其中数据端点的详细说明可查阅附录，此处可以先理解为获取设备的控制属性

• 获取数据端点

// 查询数据端点的值
XLinkGetDataPointTask getTask = XLinkGetDataPointTask.newBuilder()
        .setXDevice(xDevice)
        .setListener(new XLinkTaskListener<List<XLinkDataPoint>>() {
            @Override
            public void onError(XLinkCoreException e) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(List<XLinkDataPoint> xLinkDataPoints) {
                //返回获取到的数据端点
            }
        })
        .build();
XLinkSDK.startTask(getTask);

• 设置数据端点

//修改数据端点，控制设备
XLinkSetDataPointTask setTask = XLinkSetDataPointTask.newBuilder()
    .setXDevice(xDevice)
    .setDataPoints(dataPoints)
    .setListener(new XLinkTaskListener<XDevice>() {
        @Override
        public void onError(XLinkCoreException e) {
        }
         
        @Override
        public void onStart() {
        }
         
        @Override
        public void onComplete(XDevice xDevice) {
            //设置成功返回操作的设备对象
        }
    })
    .build();
XLinkSDK.startTask(setTask);

5、移除设备

移除设备会将设备删除掉并取消与用户的绑定关系，使用XLinkRemoveDeviceTask

XLinkRemoveDeviceTask removeTask = XLinkRemoveDeviceTask.newBuilder()
        //需要删除的设备,可以通过XLinkDeviceManager获取到对应的设备
        .setXDevice(device)
        .setListener(new XLinkTaskListener<String>() {
            @Override
            public void onError(XLinkCoreException e) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(String result) {
                //移除成功
            }
        }) 
        .build();
XLinkSDK.startTask(removeTask);

6、同步设备列表

在添加订阅成功设备之后，当前用户会与该设备存在绑定关系，在任何时候都可以从云端同步到该设备并进行设备的控制操作，使用XLinkSyncDeviceListTask

XLinkSyncDeviceListTask syncTask = XLinkSyncDeviceListTask.newBuilder()
        //同步设备后是否需要进行本地连接,默认为true
        .setConnectLocal(false)
        //设置同步设备的监听事件
        .setListener(new XLinkTaskListener<List<XDevice>>() {
            @Override
            public void onError(XLinkCoreException e) {
            }
             
            @Override
            public void onStart() {
            }
             
            @Override
            public void onComplete(List<XDevice> devices) {
                //同步成功返回当前设备列表
            }
        })
        .build();
XLinkSDK.startTask(syncTask);

四、更新说明

日期	说明
2018.09.04	修正代码表述有误的问题

上次更新：2024-05-09